海洋随笔

主题

羊村村长2026-06-16 08:59:27
4342
16.3m
0

Claude Code Agent Teams 完整使用指南 ​

适用版本：Claude Code v2.1.32+ · 实验性功能 · 推荐 Opus 4.6 及以上模型 文档参考：https://code.claude.com/docs/en/agent-teams

一、Agent Teams 是什么 ​

Agent Teams（智能体团队）是 Claude Code 在 2026 年 2 月随 Opus 4.6 一起推出的多智能体协作系统。它让多个 Claude Code 实例像一个真实的工程团队一样并行工作：

  • Team Lead（团队负责人）：你的主会话，负责拆解任务、分配工作、综合结果
  • Teammates（队员）：每个队员是独立的 Claude Code 实例，拥有独立的上下文窗口
  • Task List（共享任务列表）：所有人可见的看板，支持依赖关系，自动解锁
  • Mailbox（消息系统）：队员之间可以直接点对点发消息，不必经过 Lead 中转

一句话理解：Subagents 像你派出去跑腿的合同工，只回报结果；Agent Teams 像一支真正的 Scrum 团队，成员之间可以互相沟通、挑战、协作。

Agent Teams vs Subagents 核心区别 ​

维度SubagentsAgent Teams
上下文独立窗口，结果回传给调用者独立窗口，完全独立运行
通信只能向主代理回报队员之间直接互发消息
协调主代理统一管理共享任务列表，自主认领
你能否直接对话不能可以直接给任意队员发指令
Token 成本较低（结果摘要回主上下文）较高（每个队员都是完整实例）
适合场景独立、结果导向的小任务需要讨论、挑战、跨域协作的复杂任务

类比：Subagents 是 MapReduce —— 各自跑完汇总；Agent Teams 是 Scrum Sprint —— 成员之间持续沟通、互相交付。

二、启用与基础设置 ​

1. 检查版本 ​

bash
claude --version
# 必须 ≥ v2.1.32

2. 启用实验性标志 ​

在 ~/.claude/settings.json 中添加：

json
{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  }
}

或者在 shell 中临时启用：

bash
export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1
claude

3. 选择显示模式 ​

模式命令适用场景
in-process（默认）在单个终端内用 Shift+Down 切换队员没装 tmux、临时尝试、Windows/VS Code 终端
split panes需要 tmux 或 iTerm2队员 ≥ 3 个，需要同时盯所有进度
auto已在 tmux 中则自动分屏默认推荐

强制分屏模式：

bash
# macOS 推荐
tmux new -s claude
export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1
claude

# 或在 settings.json 中
{ "teammateMode": "tmux" }

4. 基础操作快捷键 ​

操作快捷键
切换队员视图Shift+Down（in-process 模式）
切换任务列表Ctrl+T
进入队员会话Enter
中断队员当前回合Esc
开启 Delegate Mode（建议第一时间开启）Shift+Tab

三、启动你的第一个团队 ​

启用后，用自然语言告诉 Claude 你要的团队结构。Claude 会自动生成 Lead + Teammates + 共享任务列表。

入门 Prompt 示例（来自官方文档） ​

我在设计一个 CLI 工具，帮开发者追踪代码库中的 TODO 注释。
创建一个 agent team 从不同角度探索这个问题：
- 一个队员负责 UX
- 一个队员负责技术架构
- 一个队员唱反调（devil's advocate）

这个例子之所以好，是因为三个角色彼此独立，谁也不需要等谁，符合并行的本质。

Claude 主动提议团队 ​

如果你给的任务足够复杂，Claude 会主动建议组队，你确认后才会生成。Claude 永远不会未经你同意就自动组队。

四、最佳实践（综合官方 + 社区实战） ​

✅ Practice 1：先 Plan，再 Spawn ​

Plan mode 大约花 10k tokens；走错方向的团队会花 500k+ tokens。

做法：先让主会话进入 plan 模式（Shift+Tab Shift+Tab），让它产出完整的任务拆分、文件边界、API 契约，你审过之后再让它创建团队。这是最重要的一条。

✅ Practice 2：每个队员拥有不同的文件域 ​

两个队员同时编辑同一个文件 = 互相覆盖。在 spawn prompt 里明确文件边界：

- Frontend 队员：仅修改 src/components/ 和 src/pages/
- Backend 队员：仅修改 src/api/ 和 src/db/
- Test 队员：仅修改 tests/ 和 e2e/

如果项目结构本身不分明，就在任务拆分阶段制造分明。例如不要让两人都做"重构 API 层"，而是一人做 src/api/users/，一人做 src/api/billing/。

✅ Practice 3：团队规模控制在 3–5 人 ​

官方建议起步 3–5 名队员，每人 5–6 个任务。原因：

  • Token 成本线性增长：3 个队员 ≈ 3–4 倍单会话成本
  • 协调开销非线性增长：队员越多，Lead 越容易迷失
  • 边际收益递减：3 个专注的队员往往胜过 5 个分散的队员

经验法则：15 个独立任务用 3 个队员起步，而不是 15 个队员。

✅ Practice 4：开启 Delegate Mode ​

Shift+Tab 开启后，Lead 只协调、不动手。这能避免最常见的失败模式 —— Lead 不耐烦自己写代码，留着队员闲置。

✅ Practice 5：给队员充足的 spawn context ​

队员会自动加载 CLAUDE.md、MCP servers、skills，但不会继承 Lead 的对话历史。所以 spawn prompt 必须包含：

  • 任务的"为什么"（业务背景）
  • 涉及的具体文件路径
  • 技术栈与约束
  • 输出标准（如严重等级、测试覆盖率）

反例：

Spawn 一个 security reviewer 看一下 auth 模块。

正例：

Spawn 一个 security reviewer，prompt 为：
"审查 src/auth/ 下的认证模块的安全漏洞。
重点关注 token 处理、session 管理、输入校验。
应用使用存储在 httpOnly cookies 中的 JWT token。
按严重等级（Critical/High/Medium/Low）报告问题。"

✅ Practice 6：要求计划审批（Plan Approval） ​

对高风险任务，让队员先出方案，Lead 审批后再动手：

Spawn 一个架构师队员重构认证模块。
要求在做任何修改前先获得计划审批。
审批标准：必须包含测试覆盖、不得修改数据库 schema。

✅ Practice 7：用 Hooks 设置质量闸门 ​

通过 hooks 在关键节点强制执行规则：

Hook触发时机用途
TeammateIdle队员即将空闲退出码 2 可以打回继续工作
TaskCreated任务创建时退出码 2 可以阻止创建并反馈
TaskCompleted任务标记完成时退出码 2 可以阻止完成（如未通过测试）

常见配置：测试不通过不许完成任务、lint 不过不许收工、提交信息必须含 issue ID。

✅ Practice 8：主动监督，及时纠偏 ​

你不再是开发者，你是技术 Lead，管理着一群 AI 开发者。

  • 用 Ctrl+T 看任务列表
  • 用 Shift+Down 抽查每个队员
  • 发现走偏立刻进去发消息纠正
  • 不要让团队无人看管跑 30 分钟以上

✅ Practice 9：第一次玩从研究/审查开始 ​

不要一上来就让团队写代码。先用它做：

  • 审查一个 PR
  • 调研一个库的实现方案
  • 调查一个 bug 的多个假设

这些任务边界清晰、不写代码、容易看出价值，让你先建立对团队动态的直觉。

✅ Practice 10：始终让 Lead 收尾 ​

Clean up the team

不要让队员自己清理，因为它的 team context 可能解析错误，会留下不一致的资源。

五、跨场景应用：从代码到生活 ​

Agent Teams 表面是开发工具，本质是**"多视角并行 + 共享任务板"的协作范式**。它能用在任何需要多角色协作的复杂问题上。

场景 1：项目开发（最自然的场景） ​

任务：实现一个支付集成功能

创建 agent team 实现 Stripe 支付集成。
- 队员 A（Backend）：在 src/api/payments/ 实现 API 层，使用 Stripe SDK
- 队员 B（Frontend）：在 src/components/checkout/ 实现 UI，
  等 A 完成 API 契约后开始
- 队员 C（Test）：在 tests/payments/ 写集成测试，
  和 A、B 协调测试数据格式
- 队员 D（Security Reviewer）：在 A、B 完成后审查，
  重点检查 webhook 签名验证和 PCI 合规

Lead 用 delegate mode 协调，不要自己写代码。
所有改动必须通过 lint 和 type check 才能标记完成。

关键点：A 是其他人的依赖；C 和 D 都依赖 A、B 完成 → 任务列表会自动调度。

场景 2：代码审查与重构 ​

任务：审查大型 PR

为 PR #142 创建审查团队，3 个队员：
- 安全视角：关注认证、注入、密钥泄漏
- 性能视角：N+1 查询、内存占用、热路径
- 可维护性视角：命名、模块边界、测试覆盖

每人独立审查，然后互相分享发现并挑战。
Lead 综合所有意见出最终评审。

场景 3：Bug 调试（竞争假设法） ​

这是 Agent Teams 最被低估的用法。 单个 agent 容易"找到第一个看似合理的解释就停"，团队可以同时验证多个假设。

用户报告 app 在第一条消息后就退出，没有保持连接。
Spawn 5 个队员调查不同假设，让他们互相讨论、
像科学辩论一样试图推翻彼此的理论。

假设 1：WebSocket 心跳超时
假设 2：服务端内存泄漏导致进程被杀
假设 3：客户端事件循环阻塞
假设 4：负载均衡器空闲连接被踢
假设 5：认证 token 过期

把最终共识写入 findings.md。

为什么有效：顺序调查会"锚定"在第一个理论上；多人对抗式调查能让最强的解释胜出。

场景 4：写作/内容创作 ​

创建一个写作团队，写一篇关于 AI 在医疗诊断中应用的长文：
- Researcher：调研最新论文和案例（用 web 搜索）
- Writer：基于 Researcher 输出写初稿
- Editor：审查结构、流畅度、事实准确性
- Devil's Advocate：找出最弱的论点和反例

最终交付 docs/article.md。

场景 5：工作规划与决策 ​

我们团队下个季度要选 Q4 重点项目。
创建一个决策团队探索三个候选项目：
- 队员 A：评估项目 X（市场需求、技术可行性、ROI）
- 队员 B：评估项目 Y
- 队员 C：评估项目 Z
- 队员 D：作为反方，挑战每个项目的假设

每人写一份 evaluation/{project}.md，
最后 Lead 综合并给出推荐顺序。

场景 6：创业 / 商业分析 ​

我在考虑做一个面向独立开发者的 SaaS 工具。
创建一个市场分析团队：
- 竞品研究员：列出现有的 5 个直接竞品，分析定价、功能、用户评价
- 用户痛点研究员：从 Reddit、HackerNews、X 找真实用户抱怨
- 技术可行性：评估 MVP 需要的技术栈和 6 周内能否上线
- 财务建模：基于 100/1000/10000 用户三档算单元经济性

互相分享发现，最后输出 go/no-go 决策文档。

场景 7：个人生活规划 ​

这听起来"杀鸡用牛刀"，但当你要做大决定（搬家、转行、买房）时很有用。

我在纠结是否从北京搬到深圳。
创建一个决策团队：
- 队员 A：列出搬家的所有利（事业、气候、生活成本……）
- 队员 B：列出所有弊（远离家人、空气、医疗……）
- 队员 C：调研深圳具体区域的房租、通勤、学区数据
- 队员 D：扮演反方，假设我 5 年后后悔，找出可能的原因

最后 Lead 综合，但不要替我做决定，
只给出一份让我自己能权衡的决策矩阵。

六、进阶技巧（30 条精华） ​

关于团队组成 ​

  1. Lead 用 Opus，队员用 Sonnet —— 协调需要最强模型，执行用 Sonnet 性价比更高。在 /config 里设置默认 teammate model。
  2. 角色组合而非数量：写作 = context gatherer + writer + editor；编码 = architecture + frontend + backend。
  3. 复用 Subagent 定义：在 .claude/agents/ 或 ~/.claude/agents/ 定义可复用角色（如 security-reviewer.md），spawn 时按名字引用，定义的 prompt 会追加到队员的系统提示中。
  4. 队员名字要自己起：spawn prompt 里告诉 Lead "把第一个队员叫 alice"，后续你就能精确点名。

关于 Prompt ​

  1. 不要在 Claude Code 里直接打字 —— 在 IDE 里写好 prompt 再粘贴，质量提升明显。
  2. 明确质量标准：在 prompt 顶部加 "为所有代码维持极高质量标准，把这个标准传达给所有队员"，会层层下传。
  3. 预批准常用操作：在 permissions.allow 里加上常见操作，避免每个队员都来请示。
  4. 不要用 --dangerously-skip-permissions：所有队员都会继承，风险放大。

关于运行控制 ​

  1. **Lead 在自己动手？**说一句 "Wait for your teammates to complete their tasks before proceeding"。
  2. **Lead 过早收工？**说 "Keep going, not all tasks are done"。
  3. 队员卡住了？Shift+Down 进去直接给指令，或让 Lead spawn 一个替代队员。
  4. **任务卡在 in-progress？**手动改状态，或让 Lead 提醒那个队员。
  5. 跑 30 分钟看一次：长时间无人监管 = 浪费 token。
  6. 遇到坏方向立刻中断：Esc 中断比让它跑完便宜得多。

关于成本 ​

  1. 3 队员 ≈ 3-4 倍单会话成本 —— 简单任务别组队。
  2. 重命名变量这种事用单会话，组队的协调开销远超收益。
  3. 研究/审查 ROI 最高：探索性任务并行价值大，节省的时间值回 token。
  4. 设置队员上限：把团队规模写进 CLAUDE.md，避免 Lead 失控扩编。

关于产出 ​

  1. 要求结构化输出：让每个队员把发现写到指定文件（如 findings/security.md），便于你审阅。
  2. 要求引用证据：让队员在报告里写明 "在 file:line 看到"，便于核实。
  3. 要求 severity 标注：审查类任务要求 Critical/High/Medium/Low 分级。

关于已知坑 ​

  1. Session 不能恢复 in-process 队员：/resume 后 Lead 会试图给已不存在的队员发消息，告诉它"spawn new teammates"。
  2. Shutdown 较慢：队员要跑完当前 turn 才能退。
  3. 一次只能一个团队：要新建，先 cleanup 旧的。
  4. 不能嵌套团队：队员不能再开团队，只有 Lead 能管理。
  5. Lead 身份不可转：创建团队的会话终身是 Lead。
  6. 僵尸 tmux 会话：用 tmux ls 查、tmux kill-session -t <name> 清掉。

关于工作流 ​

  1. 第一周：纯探索类任务（PR review、bug 调查、库调研），熟悉协作动态。
  2. 第二周：3 个队员的实现任务（前后端+测试），有清晰文件边界。
  3. 第三周以后：建立模板库。把每种项目的"模型分配 + 团队大小 + spawn prompt 模板"沉淀下来，下次几乎瞬时启动。

七、常见问题排查 ​

症状可能原因解决
队员没出现在 in-process 模式但没切视图Shift+Down 切换
队员没出现任务太简单，Claude 觉得不值得组队让任务再复杂一点，或显式要求组队
分屏不工作tmux 没装which tmux 检查，没有就装
权限弹窗太多没预批准在 permissions.allow 加常用操作
队员报错就停了没自动恢复机制直接进去指导，或 spawn 替代者
Lead 过早收工实验性功能的已知问题告诉它"keep going"
任务无法标记完成队员漏标手动改状态或让 Lead 催

八、什么时候不该用 Agent Teams ​

诚实的建议：90% 的日常任务不需要 Agent Teams。

❌ 单文件改动（重命名、修一个 bug、加一个字段） ❌ 任务高度串行，下一步必须等上一步（用单会话就好） ❌ 任务都要碰同一组文件（必然冲突） ❌ 你不喜欢用 plan mode，喜欢直接执行（Agent Teams 强依赖计划） ❌ 任务很小，但你想"显得高级"（纯属浪费 token）

✅ 真正的判断标准：这个任务能否拆成 3 个以上真正独立的工作流，且每个工作流的输出对其他人有价值？

如果答案是"是" —— 用 Agent Teams。 如果只是"有点平行" —— 用 subagents。 如果只是"步骤多" —— 用单会话 + plan mode。

九、心智模型转变 ​

使用 Agent Teams 之后最大的变化不是技术上的，而是角色定位：

你不再是"用 AI 的开发者"，你是"管理 AI 开发者的技术 Lead"。

这意味着：

  • 你要会拆解需求（这是 Lead 的核心能力）
  • 你要会定义文件边界（避免冲突的核心手段）
  • 你要会设计 API 契约（让平行工作能合龙）
  • 你要会抽查质量（不是逐行 review，而是抓关键风险点）
  • 你要会及时止损（一个方向跑偏了，杀掉重来比硬撑便宜）

真实工程团队管理的所有规律，在这里同样适用：清晰的任务、合理的人数、独立的工作流、及时的同步、明确的质量标准。

十、延伸资源 ​

本指南整合了 Claude Code 官方文档与社区实战经验（截至 2026 年 5 月）。Agent Teams 仍处于实验性阶段，功能与限制可能随版本更新而变化，请定期查阅官方文档获取最新信息。

最近更新